Criar um Documento para Assinatura Eletrônica

Quando um documento é criado com sucesso, a API retorna o código de status HTTP 201 Created, com os dados do documento criado no corpo da resposta. Em seguida, cada signatário receberá um email com um link para assinar o documento.

Assim que todos os signatários assinarem o documento, um evento "document.status.signed" é emitido para a URL configurada, contendo os dados da assinatura e um link para download do documento assinado em formato de PDF.

Para realizar a asssinatura de um documento, é necessário enviar o arquivo PDF a ser assinado para a API de armazenamento de arquivos. Existem duas formas: enviar a URL publicamente acessível do arquivo PDF ou enviar o arquivo PDF em base64.

Segurança

Para acessar a API, é necessário obter um token de acesso através do fluxo de autenticação OAuth2. Veja mais detalhes em Como obter acesso?

info

Ao gerar o token JWT, não esqueça de utilizar o escopo correto. Caso contrário, a requisição será rejeitada com o código de erro 401 Unauthorized.

Descrição dos campos

Campo	Tipo	Descrição
name	string	Nome do documento. Utilizado para identificar o documento a ser assinado
businessId	string	Identificador do documento no sistema do parceiro. Pode ser utilizado para identificar o documento no sistema do parceiro.
signers	array	Lista de signatários do documento
businessId	string	Identificador do signatário no sistema do parceiro. Pode ser utilizado para identificar o signatário no sistema do parceiro
name	string	Nome do signatário
email	string	Email do signatário
fileUrl	string	Opcional. URL publicamente acessível do arquivo PDF a ser assinado. Se informado, o campo file fileBase64 é ignorado
fileBase64	string	Opcional. Arquivo PDF em base64. Se informado, o campo fileUrl é ignorado.

info

Um dos campos fileUrl ou fileBase64 deve ser informado.

Requisição

POST https://api-sandbox.catalisa.com.br/doc-signature/api/v1/documents JWT scope: doc-signature/create:documents

Parâmetros

Sem parâmetros

Cabeçalhos

Nome	Valor
Authorization	Bearer <token>
Content-Type	application/json

Exemplo de Requisição informando a URL do arquivo PDF

Corpo da Requisição

{
  "name": "Contrato nº 12345",
  "businessId": "XPTO-PEDIDO-12345-001",
  "signers": [
    {
      "businessId": "XPTO-CLIENTE-12345-001",
      "name": "Fulano de Tal",
      "email": "fulano@example.com"
    }
  ],
  "fileUrl": "https://example.com/document.pdf"
}

Respostas

Código	Descrição
201	Documento criado com sucesso. Retorna os dados do documento criado
401	Não autorizado

Exemplo de uso

Javascript

const headers = new Headers();
headers.append("Authorization", "Bearer <token>");
headers.append("Content-Type", "application/json");

const body = JSON.stringify({
  name: "Contrato nº 12345",
  businessId: "XPTO-PEDIDO-12345-001",
  signers: [
    {
      businessId: "XPTO-CLIENTE-12345-001",
      name: "Fulano de Tal",
      email: "fulano@example.com",
    },
  ],
  fileUrl: "https://example.com/document.pdf",
});

const requestOptions = {
  method: "POST",
  headers: headers,
  body: body,
};

const response = await fetch(
  "https://api-sandbox.catalisa.com.br/doc-signature/api/v1/documents",
  requestOptions
);
const data = await response.json();
console.log(data);

CURL

curl --location --request POST 'https://api-sandbox.catalisa.com.br/doc-signature/api/v1/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
--data-raw '{
  "name": "Contrato nº 12345",
  "businessId": "XPTO-PEDIDO-12345-001",
  "signers": [
    {
      "businessId": "XPTO-CLIENTE-12345-001",
      "name": "Fulano de Tal",
      "email": "fulano@example.com"
    }
  ],
  "fileUrl": "https://example.com/document.pdf"
}'

Exemplo de Sucesso

{
  "data": {
    "type": "documents",
    "id": "c58a0dc6-f862-40eb-92cd-20922d1d618a",
    "attributes": {
      "status": "pending",
      "businessId": "dca749e9-e60e-490e-936a-64fbc6eb67f9",
      "signers": [
        {
          "businessId": "XPTO-CLIENTE-12345-001",
          "name": "Fulano de Tal",
          "email": "fulano@example.com"
        }
      ],
      "originalFile": "https://api-sandbox.catalisa.com.br/file-storage/api/v1/files/a59ebf3c-c88a-416c-b735-8b51df1dcb3c",
      "signedFile": "https://api-sandbox.catalisa.com.br/file-storage/api/v1/files/a59ebf3c-c88a-416c-b735-8b51df1dcb3c"
    }
  },
  "links": {
    "self": "https://api-sandbox.catalisa.com.br/doc-signature/api/v1/documents/c58a0dc6-f862-40eb-92cd-20922d1d618a"
  }
}